<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>Events in wxWidgets</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="wxWidgets, tutorial, events, C++, programming, GUI, multiplatform">
<meta name="description" content="This part of the wxWidgets tutorial covers events.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>Events</h1>


<p>
Events are integral part of every GUI application. All GUI applications 
are event-driven. An application reacts to different event types which are 
generated during its lifetime. Events are generated mainly by the user of an 
application. But they can be generated by other means as well. e.g. internet 
connection, window manager, timer.
When the application starts a main loop is created. The application sits 
in the main loop and waits for the events 
to be generated. The main loop quits, when we exit the application.
</p>

<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* NewSquare */
google_ad_slot = "0364418177";
google_ad_width = 300;
google_ad_height = 250;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 

<h2>Definitions</h2>

<p>
<b>Event</b> is a piece of application-level information from the underlying 
framework, typically the GUI toolkit.
<b>Event loop</b> is  a programming construct that waits for and dispatches 
events or messages in a program. The event loop repeatedly looks for events 
to process them. A <b>dispatcher</b> is a process which maps events to 
<b>event handlers</b>. Event handlers are methods that react to events.
</p>


<p>
<b>Event object</b> is an object associated with the event. It is usually a 
window. <b>Event type</b> is a unique event, that has been generated.
</p>


<h2>A simple event example</h2>

<p>
The traditional way to work with events in wxWidgets is to use <b>static event tables.</b> 
This was influenced by the MFC. A more flexible and modern way is to use the <b>Connect()</b> method. 
Because this way is superior to event tables, I use it throughout the wxWidgets tutorial.
</p>


<h2>Event table</h2>

<p>
In the next example, we show an example, where we use event tables. 
</p>

<div class="codehead">button.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyButton : public wxFrame
{
public:
    MyButton(const wxString&amp; title);

    void OnQuit(wxCommandEvent&amp; event);

private:
    DECLARE_EVENT_TABLE()

};
</pre>

<div class="codehead">button.cpp</div>
<pre class="code">
#include "button.h"

MyButton::MyButton(const wxString&amp; title)
       : wxFrame(NULL, wxID_ANY, title, wxDefaultPosition, wxSize(270, 150))
{

  wxPanel *panel = new wxPanel(this, wxID_ANY);
  wxButton *button = new wxButton(panel, wxID_EXIT, 
      wxT("Quit"), wxPoint(20, 20));

  Centre();
}

void MyButton::OnQuit(wxCommandEvent&amp; WXUNUSED(event))
{
    Close(true);
}

BEGIN_EVENT_TABLE(MyButton, wxFrame)
    EVT_BUTTON(wxID_EXIT,  MyButton::OnQuit)
END_EVENT_TABLE()
</pre>

<div class="codehead">main.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyApp : public wxApp
{
  public:
    virtual bool OnInit();
};
</pre>

<div class="codehead">main.cpp</div>
<pre class="code">
#include "main.h"
#include "button.h"

IMPLEMENT_APP(MyApp)

bool MyApp::OnInit()
{

    MyButton *button = new MyButton(wxT("Button"));
    button->Show(true);

    return true;
}
</pre>

<p>
In our example we create a simple button. By clicking on the button, we close the 
application. 
</p>


<pre class="explanation">
private:
    DECLARE_EVENT_TABLE()
</pre>

<p>
In the header file, we declare an event table with the DECLARE_EVENT_TABLE() macro.
</p>

<pre class="explanation">
BEGIN_EVENT_TABLE(MyButton, wxFrame)
    EVT_BUTTON(wxID_EXIT,  MyButton::OnQuit)
END_EVENT_TABLE()
</pre>

<p>
We implement an event table by mapping each event to the appropriate member function.
</p>


<h2>Example using Connect()</h2>

<p>
We will talk about a move event.
A move event holds information about move change events.
A move event is generated, when we move a window to a new position. 
The class that represents the move event is <b>wxMoveEvent</b>. 
The <b>wxEVT_MOVE</b> is an event type.
</p>


<div class="codehead">move.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class Move : public wxFrame
{
public:
  Move(const wxString&amp; title);

  void OnMove(wxMoveEvent &amp; event);

  wxStaticText *st1;
  wxStaticText *st2;

};
</pre>

<div class="codehead">move.cpp</div>
<pre class="code">
#include "move.h"

Move::Move(const wxString&amp; title)
       : wxFrame(NULL, wxID_ANY, title, wxDefaultPosition, wxSize(250, 130))
{
  wxPanel *panel = new wxPanel(this, -1);

  st1 = new wxStaticText(panel, -1, wxT(""), wxPoint(10, 10));
  st2 = new wxStaticText(panel, -1, wxT(""), wxPoint(10, 30));

  Connect(wxEVT_MOVE, wxMoveEventHandler(Move::OnMove));

  Centre();
}

void Move::OnMove(wxMoveEvent&amp; event)
{
  wxPoint size = event.GetPosition();
  st1->SetLabel(wxString::Format(wxT("x: %d"), size.x ));
  st2->SetLabel(wxString::Format(wxT("y: %d"), size.y ));
}
</pre>


<div class="codehead">main.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyApp : public wxApp
{
  public:
    virtual bool OnInit();
};
</pre>

<div class="codehead">main.cpp</div>
<pre class="code">
#include "main.h"
#include "move.h"

IMPLEMENT_APP(MyApp)

bool MyApp::OnInit()
{
    Move *move = new Move(wxT("Move event"));
    move->Show(true);

    return true;
}
</pre>

<p>
The example displays the current position of the window.
</p>

<pre class="explanation">
Connect(wxEVT_MOVE, wxMoveEventHandler(Move::OnMove));
</pre>

<p>
Here we connect a <i>wxEVT_MOVE</i> event type with the <i>OnMove()</i> method.
</p>

<pre class="explanation">
wxPoint size = event.GetPosition();
</pre>

<p>
The event parameter in the <i>OnMove()</i> method is an object specific 
to a particular event. In our case it is the instance of a <i>wxMoveEvent</i> class. 
This object holds information about the event. We can find out the current position 
by calling the <i>GetPosition()</i> method of the event.
</p>

<img src="/img/gui/wxwidgets/move.jpg" alt="Move event">
<div class="figure">Figure: Move event</div>


<h2>Event propagation</h2>


<p>
There are two types of events. Basic events and command events. They differ 
in propagation. Event propagation is travelling of events from child widgets 
to parent widgets and grand parent widgets etc. Basic events do not propagate. 
Command events do propagate. For example <i>wxCloseEvent</i> is a basic event. 
It does not make sense for this event to propagate to parent widgets. 
</p>

<p>
By default, the event that is catched in a event handler stops propagating. 
To continue propagation, we must call the <i>Skip()</i> method.
</p>

<div class="codehead">propagate.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class Propagate : public wxFrame
{
public:
  Propagate(const wxString&amp; title);
  
  void OnClick(wxCommandEvent&amp; event);

};


class MyPanel : public wxPanel
{
public: 
  MyPanel(wxFrame *frame, int id);

  void OnClick(wxCommandEvent&amp; event);
};


class MyButton : wxButton
{
public:
  MyButton(MyPanel *panel, int id, const wxString &amp;label);

  void OnClick(wxCommandEvent&amp; event);

};
</pre>

<div class="codehead">propagate.cpp</div>
<pre class="code">
#include &lt;iostream&gt;
#include "propagate.h"

const int ID_BUTTON = 1;

Propagate::Propagate(const wxString&amp; title)
    : wxFrame(NULL, wxID_ANY, title, wxDefaultPosition, wxSize(250, 130))
{
  MyPanel *panel = new MyPanel(this, -1);

  new MyButton(panel, ID_BUTTON, wxT("Ok"));

  Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, 
      wxCommandEventHandler(Propagate::OnClick));

  Centre();
}


void Propagate::OnClick(wxCommandEvent&amp; event) 
{
  std::cout &lt;&lt; "event reached frame class" &lt;&lt; std::endl;
  event.Skip();
}


MyPanel::MyPanel(wxFrame *frame, int id)
    : wxPanel(frame, id)
{
  Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, 
      wxCommandEventHandler(MyPanel::OnClick));
} 

void MyPanel::OnClick(wxCommandEvent&amp; event) 
{
  std::cout &lt;&lt; "event reached panel class" &lt;&lt; std::endl;
  event.Skip();
}


MyButton::MyButton(MyPanel *mypanel, int id, const wxString&amp; label)
    : wxButton(mypanel, id, label, wxPoint(15, 15))
{
  Connect(ID_BUTTON, wxEVT_COMMAND_BUTTON_CLICKED, 
      wxCommandEventHandler(MyButton::OnClick));
} 


void MyButton::OnClick(wxCommandEvent&amp; event) 
{
  std::cout &lt;&lt; "event reached button class" &lt;&lt; std::endl;
  event.Skip();
}
</pre>

<div class="codehead">main.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyApp : public wxApp
{
  public:
    virtual bool OnInit();
};
</pre>

<div class="codehead">main.cpp</div>
<pre class="code">
#include "main.h"
#include "propagate.h"

IMPLEMENT_APP(MyApp)

bool MyApp::OnInit()
{

    Propagate *prop = new Propagate(wxT("Propagate"));
    prop->Show(true);

    return true;
}
</pre>

<p>
In our example, we have a button on a panel. The panel is placed 
in a frame widget. We define a handler for all widgets.
</p>

<pre>
event reached button class
event reached panel class
event reached frame class
</pre>

<p>
We get this, when we click on the button. The event travels from the 
button to panel and to frame.
</p>

<p>
Try to omit some Skip() methods and see, what hapens. 
</p>


<h2>Vetoing events</h2>

<p>
Sometimes we need to stop processing an event. To do this, 
we call the method Veto(). 
</p>

<div class="codehead">veto.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class Veto : public wxFrame
{
public:
  Veto(const wxString&amp; title);

  void OnClose(wxCloseEvent&amp; event);

};
</pre>

<div class="codehead">veto.cpp</div>
<pre class="code">
#include "veto.h"


Veto::Veto(const wxString&amp; title)
    : wxFrame(NULL, wxID_ANY, title, wxDefaultPosition, wxSize(250, 130))
{

  Connect(wxEVT_CLOSE_WINDOW, wxCloseEventHandler(Veto::OnClose));
  Centre();
}

void Veto::OnClose(wxCloseEvent&amp; event) 
{
  wxMessageDialog *dial = new wxMessageDialog(NULL,
      wxT("Are you sure to quit?"), wxT("Question"),
      wxYES_NO | wxNO_DEFAULT | wxICON_QUESTION);

  int ret = dial->ShowModal();
  dial->Destroy();

  if (ret == wxID_YES) {
      Destroy();
  } else {
      event.Veto();
  }
}
</pre>

<div class="codehead">main.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyApp : public wxApp
{
  public:
    virtual bool OnInit();
};
</pre>

<div class="codehead">main.cpp</div>
<pre class="code">
#include "main.h"
#include "veto.h"

IMPLEMENT_APP(MyApp)

bool MyApp::OnInit()
{

    Veto *veto = new Veto(wxT("Veto"));
    veto->Show(true);

    return true;
}
</pre>

<p>
In our example, we process a <i>wxCloseEvent</i>. This event is called, 
when we click the X button on the titlebar, press Alt + F4 or select 
close from the system menu. In many applications, we want to prevent 
from accidentally closing the window, if we made some changes. To do 
this, we must connect the wxEVT_CLOSE_WINDOW event type. 
</p>

<pre class="explanation">
wxMessageDialog *dial = new wxMessageDialog(NULL, 
   wxT("Are you sure to quit?"), wxT("Question"),
   wxYES_NO | wxNO_DEFAULT | wxICON_QUESTION);
</pre>

<p>
During the close event, we show a message dialog.
</p>

<pre class="explanation">
if (ret == wxID_YES) {
    Destroy();
} else {
    event.Veto();
}
</pre>

<p>
Depending on the return value, we destroy the window, or veto the 
event. Notice that to close the window, we must call the <i>Destroy()</i>
method. By calling the <i>Close()</i> method, we would end up in an endless cycle.
</p>


<h2>Window identifiers</h2>

<p>
Window identifiers are integers that uniquely determine the window 
identity in the event system. 
There are three ways to create window id's.
</p>

<ul>
<li>let the system automatically create an id</li>
<li>use standard identifiers</li>
<li>create your own id</li>
</ul>

<p>
Each widget has an id parameter. This is a unique number in the event system. 
If we work with multiple widgets, we must differantiate among them.
</p>

<pre class="definition">
 wxButton(parent, -1)
 wxButton(parent, wxID_ANY)
</pre>

<p>
If we provide -1 or wxID_ANY for the id parameter, we let the wxWidgets 
automatically create an id for us. The automatically created id's are 
always negative, whereas user specified id's must always be positive. 
We usually use this option when we do not need to change the widget state. 
For example a static text, that will never be changed during the life of 
the application. We can still get the id, if we want. There is a method 
<i>GetId()</i>, which will determine the id for us.
</p>


<p>
Standard identifiers should be used whenever possible. The identifiers 
can provide some standard graphics or behaviour on some platforms.
</p>


<div class="codehead">ident.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class Ident : public wxFrame
{
public:
  Ident(const wxString&amp; title);

};
</pre>

<div class="codehead">ident.cpp</div>
<pre class="code">
#include "ident.h"

Ident::Ident(const wxString&amp; title)
    : wxFrame(NULL, wxID_ANY, title, wxDefaultPosition, wxSize(200, 150))
{

  wxPanel *panel = new wxPanel(this, -1);

  wxGridSizer *grid = new wxGridSizer(2, 3);

  grid->Add(new wxButton(panel, wxID_CANCEL), 0, wxTOP | wxLEFT, 9);
  grid->Add(new wxButton(panel, wxID_DELETE), 0, wxTOP, 9);
  grid->Add(new wxButton(panel, wxID_SAVE), 0, wxLEFT, 9);
  grid->Add(new wxButton(panel, wxID_EXIT));
  grid->Add(new wxButton(panel, wxID_STOP), 0, wxLEFT, 9);
  grid->Add(new wxButton(panel, wxID_NEW));

  panel->SetSizer(grid);
  Centre();
}
</pre>

<div class="codehead">main.h</div>
<pre class="code">
#include &lt;wx/wx.h&gt;

class MyApp : public wxApp
{
  public:
    virtual bool OnInit();
};
</pre>

<div class="codehead">main.cpp</div>
<pre class="code">
#include "main.h"
#include "ident.h"

IMPLEMENT_APP(MyApp)

bool MyApp::OnInit()
{

    Ident *ident = new Ident(wxT("Identifiers"));
    ident->Show(true);

    return true;
}
</pre>

<p>
In our example we use standard identifiers on buttons. On Linux, the 
buttons have small icons.
</p>

<img src="/img/gui/wxwidgets/identifiers.jpg" alt="Identifiers">
<div class="figure">Figure: Identifiers</div>

<p>
In this chapter, we talked about events in wxWidgets.
</p>

<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div>  
<br> 


<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified August 27, 2007  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>
